Conversation
There was a problem hiding this comment.
Pull request overview
This PR restructures and refreshes the project documentation by consolidating many explanation pages into fewer, broader documents and updating links across the Python package docs, Quarto site, examples, and R vignettes so they point at the new locations.
Changes:
- Consolidates/renames several explanation pages (e.g., critical difference, pairwise comparison, metric-set diagnostics, heterogeneity, choice agreement) and removes superseded pages.
- Updates internal links throughout examples/vignettes/how-tos/tutorials to point at the new documentation structure (including new anchors).
- Minor wording/spelling polish and housekeeping (.gitignore for Quarto artifacts, Quarto nav updates).
Reviewed changes
Copilot reviewed 58 out of 59 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| src/beam/mcda/comet.py | Updates docstring reference to new docs location for COMET. |
| README.md | Renames “Licence” heading to “License”. |
| r/beam/vignettes/ranking.Rmd | Adds links to explanation pages; retitles sections for clarity. |
| r/beam/vignettes/metric-diagnostics.Rmd | Adds links to metric diagnostics explanations; simplifies headings. |
| r/beam/vignettes/heterogeneity.Rmd | Adds links to heterogeneity explanations; minor wording edits. |
| r/beam/vignettes/cross-benchmark.Rmd | Adds links to updated explanation pages; minor heading edits. |
| r/beam/vignettes/cell-type-annotation.Rmd | Updates links/headings to match new explanation structure. |
| index.qmd | Refreshes landing-page intro and “Where to start” links to new docs. |
| examples/transportation/transportation.qmd | Updates explanation links (critical difference, COMET anchor, pairwise comparison anchors, etc.). |
| examples/scenarios/scenarios.qmd | Updates explanation links (critical difference, pairwise comparison anchors, heterogeneity page). |
| examples/openproblems/openproblems.qmd | Updates explanation links (metric-set diagnostics, heterogeneity, pairwise comparison). |
| examples/m4/m4.qmd | Updates explanation links (critical difference, heterogeneity, pairwise comparison, spec curve anchor). |
| examples/duo2018/duo2018.qmd | Updates explanation links (critical difference, pairwise comparison, heterogeneity). |
| examples/cross_benchmark/cross_benchmark.qmd | Updates headings/links around cross-benchmark variance decomposition. |
| examples/cell_type_annotation/cell_type_annotation.qmd | Updates links (choice agreement, critical difference, pairwise comparison) and narrative wording. |
| docs/tutorials/quickstart.md | Updates wording and dataset concordance link to consolidated page. |
| docs/how-to/run-heterogeneity-from-the-cli.md | Updates explanation links to consolidated heterogeneity content. |
| docs/how-to/run-from-beam-yaml.md | Rewords reproducibility section and adds link to rerun-from-manifest. |
| docs/how-to/rerun-from-manifest.md | Small wording tweak clarifying manifest purpose. |
| docs/how-to/plot-a-beam-run.md | Updates critical-difference explanation link and wording. |
| docs/explanations/weighting-schemes.md | Updates spec-curve link to new anchor location. |
| docs/explanations/transitivity.md | Removed (content consolidated elsewhere). |
| docs/explanations/stato-term-proposals.md | Removed (content moved into ontology-mappings). |
| docs/explanations/specification-curve.md | Removed (content moved into rank-sensitivity). |
| docs/explanations/skillings-mack.md | Removed (content moved into critical-difference). |
| docs/explanations/reliability.md | Removed (content moved into metric-set-diagnostics). |
| docs/explanations/reference-levels.md | Updates links to consolidated pairwise comparison page/anchors. |
| docs/explanations/rank-sensitivity.md | Renamed/expanded to include specification-curve content and anchors. |
| docs/explanations/pairwise-superiority.md | Removed (content moved into pairwise-method-comparison). |
| docs/explanations/pairwise-method-comparison.md | New consolidated page covering superiority/transitivity/Bayesian comparison. |
| docs/explanations/openproblems-as-a-data-source.md | Updates heterogeneity link to consolidated page/anchors. |
| docs/explanations/ontology-mappings.md | Embeds former STATO proposal content; adds sectioned structure. |
| docs/explanations/normalization-and-scales.md | Updates link to choice-agreement normalization section. |
| docs/explanations/normalization-agreement.md | Removed (content moved into choice-agreement). |
| docs/explanations/network-meta-analysis.md | Updates heterogeneity linkage and keeps cross-reference to source variance decomposition. |
| docs/explanations/missing-data.md | Updates COMET and critical-difference/Skillings-Mack links/anchors; wording tweak. |
| docs/explanations/metric-set-diagnostics.md | New consolidated page for validity/reliability/dimensionality. |
| docs/explanations/method-by-dataset-heterogeneity.md | New consolidated page for heterogeneity models (mixed-effects, BT trees, PL, beta). |
| docs/explanations/heterogeneity-mixed-effects.md | Removed (content moved into method-by-dataset-heterogeneity). |
| docs/explanations/heterogeneity-bradley-terry.md | Removed (content moved into method-by-dataset-heterogeneity). |
| docs/explanations/funky-heatmaps-and-robustness.md | Updates links and tightens prose; points to consolidated pages. |
| docs/explanations/full-rankings-and-bounded-metrics.md | Removed (content moved into method-by-dataset-heterogeneity). |
| docs/explanations/dimensionality.md | Removed (content moved into metric-set-diagnostics). |
| docs/explanations/dataset-discrimination.md | Removed (content moved into dataset-concordance-and-discrimination). |
| docs/explanations/dataset-concordance-and-discrimination.md | Expanded to include dataset discrimination section; updates internal links. |
| docs/explanations/critical-difference.md | New consolidated page covering Friedman/Nemenyi and Skillings-Mack. |
| docs/explanations/convergent-discriminant-validity.md | Removed (content moved into metric-set-diagnostics). |
| docs/explanations/comparing-methods-across-datasets.md | Removed (superseded by critical-difference). |
| docs/explanations/comet.md | Removed (COMET documentation moved into aggregation-methods). |
| docs/explanations/choice-agreement.md | New consolidated page for aggregation & normalization agreement. |
| docs/explanations/cards-and-pipeline.qmd | Retitles page for clarity. |
| docs/explanations/card-data-consistency.md | Tightens wording and clarifies responsibility of the audit. |
| docs/explanations/bayesian-comparison.md | Removed (content moved into pairwise-method-comparison). |
| docs/explanations/attribution-synthesis.md | Updates links to consolidated heterogeneity/spec-curve anchors. |
| docs/explanations/analysis-blinding.md | Clarifies that unblinding renames only; updates spec-curve link. |
| docs/explanations/aggregation-methods.md | Updates COMET documentation inline; points aggregation agreement to choice-agreement. |
| docs/explanations/aggregation-agreement.md | Removed (content moved into choice-agreement). |
| .gitignore | Ignores Quarto build artifacts and quarto notebooks. |
| _quarto.yml | Updates site nav to point at consolidated explanation pages and removes retired pages. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - [Cards and pipeline](docs/explanations/cards-and-pipeline.qmd). What a metric card encodes and how is it processed. | ||
| - [Comparing methods across datasets](docs/explanations/comparing-methods-across-datasets.md). Diagnostics on method-dataset performance variability. | ||
| - [Cards and pipeline](docs/explanations/cards-and-pipeline.qmd). What a metric card encodes and how it is processed. | ||
| - [Comparing methods across datasets](docs/explanations/critical-difference.md). Diagnostics on method-dataset performance variability. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.